---
title: "permissions_query_syntax_error"
description: "Invalid syntax or characters in verifyKey permissions query"
---

<Danger>`err:user:bad_request:permissions_query_syntax_error`</Danger>

```json Example
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "Syntax error in permission query: unexpected token 'AND' at position 15. Expected permission name or opening parenthesis.",
    "status": 400,
    "title": "Bad Request",
    "type": "https://unkey.com/docs/api-reference/errors-v2/user/bad_request/permissions_query_syntax_error",
    "errors": [
      {
        "location": "body.permissions",
        "message": "unexpected token 'AND' at position 15",
        "fix": "Check your query syntax. AND/OR operators must be between permissions, not at the start or end"
      }
    ]
  }
}
```

## What Happened?

This error occurs when the permissions query in your `verifyKey` request contains invalid syntax or characters. This can happen due to:

- **Invalid characters** in permission names (lexical errors)
- **Incorrect query structure** like missing operands or unmatched parentheses (syntax errors)
- **Malformed expressions** that don't follow the expected grammar

## Permissions Query Requirements

The `verifyKey` endpoint accepts a permissions query string that must follow these rules:

### Valid Characters

The query parser accepts these characters:

- **Permissions**: Must follow the permission slug format (alphanumeric, dots, underscores, hyphens)
  - **Letters**: `a-z`, `A-Z`
  - **Numbers**: `0-9`
  - **Dots**: `.` for permission namespacing
  - **Underscores**: `_` in identifiers
  - **Hyphens**: `-` in identifiers
- **Query operators**: `AND`, `OR` (case insensitive)
- **Grouping**: `(` `)` for parentheses
- **Whitespace**: Spaces, tabs and new lines for separation (ignored by parser)

Everything else is not allowed.

### Query Structure

A permissions query can be:

1. **A single permission**: `permission_1`
2. **Multiple permissions with AND**: `permission_1 AND permission_2`
3. **Multiple permissions with OR**: `permission_1 OR permission_2`
4. **Grouped expressions**: `(permission_1 OR permission_2) AND permission_3`

**Key rules:**
- Permission names must be valid permission slugs (letters, numbers, dots, underscores, hyphens)
- Use `AND` when all permissions are required
- Use `OR` when any of the permissions is sufficient
- Use parentheses `()` to group expressions and control precedence
- Operators are case insensitive: `AND`, `AnD`, `and` all work.

## Common Errors and Solutions

### 1. Invalid Characters
```bash
# ❌ Invalid - contains special characters
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission$1 OR permission@2"
  }'

# ✅ Valid - use underscores or hyphens
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 OR permission_2"
  }'
```

### 2. Missing Operands
```bash
# ❌ Invalid - AND without right operand
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 AND"
  }'

# ✅ Valid - complete AND expression
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 AND permission_2"
  }'
```

### 3. Unmatched Parentheses
```bash
# ❌ Invalid - missing closing parenthesis
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "(permission_1 AND permission_2"
  }'

# ✅ Valid - balanced parentheses
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "(permission_1 AND permission_2)"
  }'
```

### 4. Empty Parentheses
```bash
# ❌ Invalid - empty parentheses
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 AND ()"
  }'

# ✅ Valid - parentheses with content
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 AND (permission_2 OR permission_3)"
  }'
```

### 5. Incorrect Operator Placement
```bash
# ❌ Invalid - operator at start
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "OR permission_1"
  }'

# ✅ Valid - operators between permissions
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 OR permission_2"
  }'
```

## Valid Query Examples

### Simple Permission
```bash
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1"
  }'
```

### AND Operation
```bash
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 AND permission_2"
  }'
```

### OR Operation
```bash
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "permission_1 OR permission_2"
  }'
```

### Complex Expressions
```bash
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "(permission_1 OR permission_2) AND permission_3"
  }'
```

### Nested Expressions
```bash
curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_XXXX" \
  -d '{
    "key": "sk_123",
    "permissions": "((permission_1 OR permission_2) AND permission_3) OR permission_4"
  }'
```

## Valid Permission Formats

### Simple Names
- `permission_1`
- `user_read`
- `admin-access`

### Namespaced Permissions
- `api.users.read`
- `billing.invoices.create`
- `workspace.settings.update`

### Mixed Formats
- `user_management.create`
- `billing-service.view`
- `service123.feature_a.read`


## Context

This error is specific to the `verifyKey` endpoint's permissions query parsing. The query is validated at the application level to ensure it conforms to the expected permission query language syntax. Basic validation like empty strings and length limits are handled at the OpenAPI level before reaching this parser.
